Guide to Python
			       Coding Style

The goal is to produce "self-documenting" code.  This means sufficient
information should be encapsulated within your code to convey meaning to
OTHER PEOPLE.  (Language interpreters and compilers can optimize your code
better than you probably can, so let them work for you!)

File structure
 - Use Unix file encoding (\n rather than Windows' \r\n)
 - First line, always specify: #! /usr/bin/env python
(This accommodates Unix and Windows/Cygwin.)
 - Second, use Python's DocString (rather than block comment).
Provide a one line summary, name of file, Subversion or CVS $Id$ tag then
describe usage and what this beast does at a high level.
 - Third, import all modules.  (Modify sys.path here if necessary.)
 - Fourth, define all classes.
 - Use one class per file (apart from container classes that specify "pass").
 - Name of file should reflect or match principal class name.
 - Organize methods within classes in top-down fashion.
 - Keep publicly accessible methods towards top, private towards bottom of file.
 - Supply conditional entry point rather than explicit execution.
   if __name__=="__main__":
       buddies = Lumberjacks()
       buddies.DoSomething("interesting")
 - Finally, supply minimal comment marking end of file (for printing) such as #End.
 - When printing source code files, reconsider and just say no!
 - If you must kill trees, use py2html (or HTMLize within Emacs) for color printers.

Naming
 - Use meaningful names for variables, functions, classes and files.
 - Use mixed case names (e.g., OpenNetworkPort() or FilePath).
 - AVOID single letter variables, even in loops!
 - Names intended to be called by external classes start with Uppercase.
 - Named intended to be private (local scope only) start with lowercase.
 - To prevent mistyping long names, use M-/ for word completion in Emacs
(e.g., typing "OpenN" or even just "Op" then ALT-/ provides OpenNetworkPort).

Statements
 - Introduce intermediate steps to illustrate logic.
 - Omit unnecessary parenthesis especially within if/for/while clauses.

Comments
 - Always explain *intent* (why) rather than summarize (who, what, how).

Note: If you're inclined to describe who, what, how or when, instead go back
to your code, and make variables & function names more descriptive!

 - If you must explain who or what, preserve commented "print" statements
with descriptive text.
 
Constants
 - AVOID hard-coded numbers or strings in code body.  Define constants instead.
 - Define constants as class member fields (or at top-level if you have no class).
 - Define constants at top of a file, just beneath all "import" statements.

Whitespace
 - Leave a blank line following the end of an indented block of code.
 - Leave two empty lines between function or class method definitions.
 - Leave three or more empty lines between multiple classes within single file.

Exceptions
 - Raising exceptions only when absolutely necessary
 - NEVER for normal program flow
 - Best practices: let exceptions "bubble up" to top-most level.
 - Test case failures return value, NEVER raising exception

Errors versus Failures
 - Denote test case "failures" versus "errors" beyond scope of individual test

Classes
 - Please provide __str__() for pretty-printing your class objects.
 - Use class-level DocString for explaining motivation and implementation
intentions at very high level (e.g., indicate Design Patterns used).

Functions and Methods
 - Put "assert" statements or sanity checks at beginning.
 - Put "return" statements at the end.
 - Retain commented "print" statements used during debugging instead of text